Inside Macintosh: QuickTime Components /

Chapter 6 - Sequence Grabber Channel Components

Using Sequence Grabber Channel Components

In response to application requests, sequence grabber components can use channel components in two ways: to play digitized data for the user or to save captured data in a QuickTime movie. The process of playing digitized data is called previewing; saving captured data in a movie is called recording. Applications can use previewing to allow the user to prepare to make a recording. Applications that use previewing can move directly from the preview operation to a record operation, without stopping the process.

The next two sections provide an overview of preview and record operations. A third section discusses the callback functions that are supported by some channel components.

Previewing

Previewing captured data involves playing that data for the user as it is digitized. For video data, this means displaying the video images on the computer screen. For audio data, this means playing the sound through the computer's sound system. The following paragraphs outline the steps the sequence grabber component follows to preview captured data.

1. First, the sequence grabber component opens a connection to your channel component, using the Component Manager's OpenComponent function. The sequence grabber component then calls your SGInitChannel function to initialize your component. For more on SGInitChannel, see page 6-36.
2. The sequence grabber component then configures your channel component for the preview operation. The SGSetGWorld function (described on page 6-37) sets the graphics world in which the preview is to be displayed. The SGSetChannelUsage function (described on page 6-46) specifies that your channel is to be used for previewing. The application can then use the appropriate channel configuration functions to prepare your channel for the preview operation. For video channels, it uses the functions discussed in "Configuration Functions for Video Channel Components" beginning on page 6-59. For sound channels, the sequence grabber uses the functions discussed in "Configuration Functions for Sound Channel Components" beginning on page 6-74.
3. The sequence grabber component starts the preview operation by calling your SGStartPreview function (described on page 6-38). The sequence grabber component then begins collecting data from all of the channels participating in the preview and plays that data appropriately. The sequence grabber component can pause and restart the preview by calling the SGPause function (described on page 6-42). The sequence grabber component uses the SGStop function (described
   on page 6-41) to stop the preview. During the preview operation, the sequence grabber component calls your SGIdle function (described on page 6-40) frequently, so that your channel can perform its operation.
4. When the application is done previewing, the sequence grabber component can start recording or close its connection to your component.

Recording

During a record operation, a sequence grabber component collects the data it captures and formats that data into a QuickTime movie. During a record operation, the sequence grabber component can also play the captured data for the user.

The following paragraphs discuss the steps the sequence grabber component follows to record captured data.

1. As with a preview operation, the sequence grabber component establishes a connection to your channel component by calling the Component Manager's OpenComponent function. It then initializes your component by calling your SGInitChannel function (described on page 6-36).
2. The sequence grabber component then configures your component for the record operation. The SGSetGWorld function (described on page 6-37) sets the graphics world in which the data is to be displayed. The SGSetChannelUsage function (described on page 6-46) specifies each channel that is to be used for recording. At this time, the sequence grabber component can also specify whether your component is to play its data while recording. The application can then use the appropriate channel configuration functions to prepare your channel for the record operation. For video channels, it uses the functions discussed in "Configuration Functions for Video Channel Components" beginning on page 6-59. For sound channels, the sequence grabber uses the functions discussed in "Configuration Functions for Sound Channel Components" beginning on page 6-74.
3. The sequence grabber component starts the record operation by calling your SGStartRecord function (described on page 6-39). The sequence grabber component then begins collecting data from the channels it has assigned, stores the data in a QuickTime movie, and, optionally, plays that data appropriately. The sequence grabber can pause and restart the record process by calling the SGPause function (described on page 6-42). During the record operation, the sequence grabber component calls your SGIdle function (described on page 6-40) frequently, so that your channel can perform its operation. The sequence grabber component uses the SGStop function (described on page 6-41) to stop the record operation. At this time, your component saves the movie in the appropriate movie file if the sequence grabber component instructs your component to do so by calling your SGWriteSamples function (described on page 6-41).
4. When the application is done recording, it either returns to previewing or closes its connection to your component.

Working With Callback Functions

Sequence grabber components provide callback functions that allow application developers to customize some aspects of capturing video data. It is your channel component's responsibility to call these callback functions at specified points in the data capture process. The application's function can then perform any special processing that is appropriate for the application. For example, an application can overlay text, such as a frame number, on each frame of video data as it is captured. These functions are discussed in detail in the next section.

Note

Sound channel components do not support any callback functions.

Using Callback Functions for Video Channel Components

Sequence grabber components allow application developers to define a number of callback functions in their applications. Your channel component calls these functions at specific points in the process of collecting, compressing, and displaying the source visual data. By defining callback functions, a developer can control the process more precisely or customize the operation of the sequence grabber component and its channel components.

For example, a developer could use a callback function to draw a frame number on each video frame as it is collected. In this case, the developer could use either a compress callback function or a grab-complete callback function. You call the compress function after each frame is collected, in order to compress the frame. You call the grab-complete function just before the compress function or as soon as the frame has been captured.

Note that your channel component need not call each and every callback function. If some functions are inappropriate to the operation of your channel, do not call them. However, if your component calls one function of a pair, be sure to call the other. For example, if your component calls an application's grab function, you must also call its grab-complete function.

The sequence grabber component uses the SGSetVideoBottlenecks function to assign callback functions to your video channel. The SGGetVideoBottlenecks function allows the sequence grabber to determine the callback functions that have been assigned to your video channel. See the chapter "Sequence Grabber Components" in this book for details on SGSetVideoBottlenecks and SGGetVideoBottlenecks.

The following application-defined functions are supported by video channels and are described in the chapter "Sequence Grabber Components" in this book.

MyAddFrameFunction	MyGrabCompressCompleteFunction
MyCompressCompleteFunction	MyGrabFunction
MyCompressFunction	MyTransferFrameFunction
MyDisplayFunction
MyGrabCompleteFunction

Using Utility Functions for Video Channel Component Callback Functions

Sequence grabber components provide a number of functions that application-defined functions can use. Several channel functions support those sequence grabber
component functions.

The sequence grabber component uses the SGGetBufferInfo function to obtain information about a buffer that contains data to be manipulated by a callback function. Application callback functions can use the SGGetBufferInfo function to obtain information about a buffer that you have passed. This information is valid only
during record operations, or after your channel has been prepared to record. The SGGetBufferInfo function is described in detail in the chapter "Sequence Grabber Components" in this book.

The following functions provide default behavior for application-defined grab, grab-complete, display, compress, compress-complete, add-frame, transfer-frame, display-compress, and grab-compress-complete functions:

• Your video channel component's SGGrabFrame function provides the default behavior for an application's grab function. Applications should call this function only from their grab function.
• Your channel component's SGGrabFrameComplete function provides the default behavior for an application's grab-complete function. Applications should call this function only from their grab-complete functions.
• Your channel component's SGDisplayFrame function provides the default behavior for an application's display function. Applications should call this function only from their display functions.
• Your video channel component's SGCompressFrame function provides the default behavior for an application's compress function. Applications should call this function only from their compress functions.
• Your channel component's SGCompressFrameComplete function provides the default behavior for an application's compress-complete function. Applications should call this function only from their compress-complete functions.
• Your component's SGAddFrame function provides the default behavior for an application's add-frame function. Applications should call this function only from their add-frame functions.
• Your component's SGTransferFrameForCompress function provides the default behavior for an application's transfer-frame function. Applications should call this function only from their transfer-frame functions.
• Your component's SGGrabCompressComplete function provides the default behavior for an application's grab-compress-complete function. Applications should call this function only from their grab-compress-complete function.
• Your component's SGDisplayCompress function provides the default behavior for an application's display-compress function. Applications should call this function only from their display-compress function.

---

Subtopics

Previewing

Recording

Working With Callback Functions

Using Callback Functions for Video Channel Components

Using Utility Functions for Video Channel Component Callback Functions

Main | Top of Section | What's New | Apple Computer, Inc. | Find It | Feedback | Help